Skip Headers

Oracle® Database PL/SQL Packages and Types Reference 10g Release 2 (10.2) Part Number B14258-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next

# 75 DBMS_RANDOM

The `DBMS_RANDOM` package provides a built-in random number generator. `DBMS_RANDOM` is not intended for cryptography.

This chapter contains the following topics:

- Using DBMS_RANDOM

  - Security Model

  - Operational Notes

- Summary of DBMS_RANDOM Subprograms

## Using DBMS_RANDOM

- Security Model

- Operational Notes

### Security Model

This package should be installed as `SYS`. By default, the package is initialized with the current user name, current time down to the second, and the current session.

### Operational Notes

- `DBMS_RANDOM.RANDOM` produces integers in [-2^^31, 2^^31).

- `DBMS_RANDOM.VALUE` produces numbers in [0,1) with 38 digits of precision.

DBMS_RANDOM can be explicitly initialized, but does not need to be initialized before calling the random number generator. It will automatically initialize with the date, userid, and process id if no explicit initialization is performed.

If this package is seeded twice with the same seed, then accessed in the same way, it will produce the same results in both cases.

In some cases, such as when testing, you may want the sequence of random numbers to be the same on every run. In that case, you seed the generator with a constant value by calling one of the overloads of `DBMS_RANDOM.SEED`. To produce different output for every run, simply to omit the call to "Seed" and the system will choose a suitable seed for you.

## Summary of DBMS_RANDOM Subprograms

Table 75-1 DBMS_RANDOM Package Subprograms

Subprogram | Description
--- | ---
INITIALIZE Procedure | Initializes the package with a seed value
NORMAL Function | Returns random numbers in a normal distribution
RANDOM Procedure | Generates a random number
SEED Procedures | Resets the seed
STRING Function | Gets a random string
TERMINATE Procedure | Terminates package
VALUE Functions | This function gets a random number, greater than or equal to 0 and less than 1, with 38 digits to the right of the decimal (38-digit precision), while the overloaded function gets a random Oracle number x, where x is greater than or equal to `low` and less than `high`

Note: The INITIALIZE Procedure, RANDOM Procedure and the TERMINATE Procedure are all obsolete and, while currently supported, are included in this release for legacy reasons only.

### INITIALIZE Procedure

This procedure initializes the generator (but see Usage Notes).

Syntax

    DBMS_RANDOM.INITIALIZE (
       val  IN  BINARY_INTEGER);

Pragmas

    PRAGMA restrict_references (initialize, WNDS)

Parameters

Table 75-2 INITIALIZE Procedure Parameters

Parameter | Description
--- | ---
`val` | The seed number used to generate a random number.

Usage Notes

This procedure is obsolete as it simply calls the SEED Procedures.

### NORMAL Function

This function returns random numbers in a standard normal distribution.

Syntax

    DBMS_RANDOM.NORMAL
      RETURN NUMBER;

Pragmas

    PRAGMA restrict_references (normal, WNDS)

Return Values

Table 75-3 NORMAL Procedure Parameters

Parameter | Description
--- | ---
`number` | Returns a random number.

### RANDOM Procedure

This procedure generates a random number (but see Usage Notes).

Syntax

    DBMS_RANDOM.RANDOM
       RETURN binary_integer;

Pragmas

    PRAGMA restrict_references (random, WNDS)

Return Values

Table 75-4 RANDOM Procedure Parameters

Parameter | Description
--- | ---
`binary_integer` | Returns a random integer greater or equal to -power(2,31) and less than power(2,31).

Usage Notes

This procedure is obsolete and, although it is currently supported, it should not be used.

### SEED Procedures

This procedure resets the seed.

Syntax

    DBMS_RANDOM.SEED (
       seed  IN  BINARY_INTEGER);

    DBMS_RANDOM.SEED (
       seed  IN  VARCHAR2);

Pragmas

    PRAGMA restrict_references (seed, WNDS);

Parameters

Table 75-5 SEED Procedure Parameters

Parameter | Description
--- | ---
`seed` | Seed number or string used to generate a random number.

Usage Notes

The seed can be a string up to length 2000.

### STRING Function

This function gets a random string.

Syntax

    DBMS_RANDOM.STRING
       opt  IN  CHAR,
       len  IN  NUMBER)
      RETURN VARCHAR2;

Pragmas

    PRAGMA restrict_references (string, WNDS)

Parameters

Table 75-6 STRING Function Parameters

Parameter | Description
--- | ---
`opt` | Specifies what the returning string looks like: 'u', 'U' - returning string in uppercase alpha characters 'l', 'L' - returning string in lowercase alpha characters 'a', 'A' - returning string in mixed case alpha characters 'x', 'X' - returning string in uppercase alpha-numeric characters 'p', 'P' - returning string in any printable characters. Otherwise the returning string is in uppercase alpha characters.
`len` | The length of the returning string.

Return Values

Table 75-7 STRING Function Return Values

Parameter | Description
--- | ---
`VARCHAR2` | Returns a `VARCHAR2`.

### TERMINATE Procedure

When you are finished with the package, call the TERMINATE procedure (but see Usage Notes)

Syntax

    DBMS_RANDOM.TERMINATE

Usage Notes

This procedure performs no function and, although it is currently supported, it is obsolete and should not be used.

### VALUE Functions

The basic function gets a random number, greater than or equal to 0 and less than 1, with 38 digits to the right of the decimal (38-digit precision). Alternatively, you can get a random Oracle number x, where x is greater than or equal to `low` and less than `high`.

Syntax

    DBMS_RANDOM.VALUE
      RETURN NUMBER;

    DBMS_RANDOM.VALUE(
      low  IN  NUMBER,
      high IN  NUMBER)
    RETURN NUMBER;

Parameters

Table 75-8 VALUE Function Parameters

Parameter | Description
--- | ---
`low` | The lowest number in a range from which to generate a random number. The number generated may be equal to `low.`
`high` | The highest number below which to generate a random number. The number generated will be less than `high.`

Return Values

Table 75-9 VALUE Function Return Values

Parameter | Description
--- | ---
`NUMBER` | Returns an Oracle Number.